                PicoMite - The story so far - Very Provisional Docs

* Loading MMBasic the first time
The Raspberry Pi Pico has its own bootloader in ROM. If you download matherp's
zip of the uf2 file that's all you need.

First, make sure the lead you use has data signals! It sounds a bit obvious
but sometimes the leads supplied with chargers are power-only types and have
no data cores.

Connect your Pico to your PC while holding the BOOTSEL button down. It should
be recognised as a new drive called RPI-RP2(like a USB stick).
Open the drive and drag matherp's uf2 file (not the zip) into it.
You see a bargraph while it copies, then the new drive disappears and the Pico
reboots. After a few seconds the green light on the PicoMite starts to flash
1s on, 1s off. It's now running MMBasic.


*Warning* There is currently a bug preventing new installs of a43 onwards onto
a new Pico. The workaround is to load a42 first then update to the new. version
using the UPDATE FIRMWARE system introduded with a14 and described below.


If, after a couple of attempts, you can't get the green light to flash
(indicating that the firmware has loaded correctly and is now running) then it
is possible that your Pico has arrived with a corrupted flash chip. The answer
is to first load a little uf2 file called flash_nuke which can be found here:
https://learn.adafruit.com/getting-started-with-raspberry-pi-pico-circuitpython/circuitpython
or here:
https://www.raspberrypi.org/documentation/rp2040/getting-started/#board-specifications
It's worth keeping a copy of this file just in case you have problems in future

You'll need to connect to your PicoMite using a termiinal program. Tera Term is
recommended for Windows.
Note: Don't bother looking for the uf2 file on the Pico or attempting to save
anything else to it. The bootloader is only a dummy drive, not a real one.
Everything else apart from a uf2 file is simply ignored.



This document refers to alpha releases of the software by release number,
Things change continually, so this is more of a time line than a manual.

From a14 the BOOTSEL button is rarely needed as UPDATE FIRMWARE can be used.
* Use
* OPTION RESET
* FLASH ERASE ALL
* VAR CLEAR
* to clean up before and after loading the alpha releases

Programs can be saved, loaded & erased from 10 flash memory areas:

FLASH ERASE n ' erases a flash program slot n=1 to 10
FLASH ERASE ALL ' erases all flash program slots
FLASH LIST 'Display list of flash area 1-10 contents
FLASH SAVE n ' Saves the current program to the flash slot specified
FLASH LOAD n ' Loads a program from the specified flash spot
FLASH RUN n ' Runs a program from the specified flash spot, clears all variables
FLASH CHAIN n ' Runs a program from the specified flash spot, leaves all
variables intact. Effectively your program can be much bigger than RAM allows.

OPTION AUTORUN OFF|ON|n where n is the flash program slot to be loaded and run
automatically on power-on or reset.




*** OPTIONS ***
I'll try to keep this section updated as we go along. Note, options may change!
See the relevant releases for details.
+ Options are remembered through power-off. 

. OPTION LIST - show all the set options
. OPTION RESET - clears all options
. OPTION <option_name> RESET - clears just option_name

+ OPTION AUTORUN OFF|ON|n
+ OPTION POWER PFM|PWM - a14
+ OPTION CPUSPEED cpuspeedinkhz - a17
+ OPTION SYSTEM SPI CLKpin, MOSIpin, MISOpin - a21
+ OPTION SDCARD CSpin, speed - a27
+ OPTION SYSTEM I2C sdapin, sclpin - a27
+ OPTION LCDPANEL type, RSpin, RESETpin, LCDCSpin - a21/a29
+ OPTION TOUCH CSpin, IRQpin [,BEEPpin] - a35
+ OPTION RTC AUTO ENABLE/DISABLE - a36
+ OPTION MEMORY No_of_GUI_controls, program_memory_size - a36
+ OPTION COUNT pin1, pin2, pin3, pin4 - a38
+ OPTION PIN nbr - a43
+ OPTION AUDIO GP18,GP19 - a48


==============================================================================

a3
LIST COMMANDS
LIST OPTIONS
settick & watchdog working

------------------------
a4
PIN() can use either Picomite pin numbers or GPn references (see a19)

------------------------
a10
PIN(41) or PIN(GP25) can be put under user control instead of 'heartbeat' flasher
SETPIN 41, DOUT|HEARTBEAT
SETPIN GP25, DOUT|HEARTBEAT

------------------------
a12
PRINT PIN(TEMP) to read the temperature of the chip
Analogue input available on GP26, GP27 & GP28

------------------------
a13
HUMID pin, temp!, humid!, type   *** SEE a34 for changes ***
type=1 for DHT11 or omitted for DHT22
PORT()

------------------------
a14
OPTION POWER PFM|PWM
defaults to PFM mode
UPDATE FIRMWARE

------------------------
a15
SD card no longer configured by default.
OPTION SDCARD  SD_CLKpin, Option.SD_MOSIpin, SD_MISOpin, SD_CSpin
*** See a21 for changes to the above ***
for original connections use OPTION SDCARD 4,5,6,7
Available RAM reduced from 96k to 80k. 
About 50% increase in speed.

------------------------
a17
OPTION CPUSPEED cpuspeedinkhz
Defaults to 125000 with options cleared. 48000-250000 can be selected.

------------------------
a19
Up to 8 PWM channels (0-7) can be used. Each of these can have it's own
frequency.Each channel can have up to two outputs (A & B), which can have the
same or different duty cycle (0-100%). This gives a total of 16 PWM outputs.
The duty cycle can be a float value.

SETPIN pin, PWMnx.
PWM channel, frequency, [dutyA] [,dutyB]
PWM channel, OFF

e.g.

SETPIN 1,PWM0A    'Provisionally allocate pin 1 (GP0) to PWM0A
SETPIN 2,PWM0B    'Provisionally allocate pin 2 (GP1) tp PWM0B
PWM 0,1000,33,67  'Frequency is 1kHz for PWM0x, PWM0A is 33%, PWM0B is 67%
                  'The pins are now locked to PWM usage until PWM 0,OFF
PWM 0,OFF         'PWM0A and PWM0B are both off and the pins are released

The setpin can be changed until the PWM command is issued. At that point the
pin becomes locked to PWM until PWM n,OFF is issued
There are 8 separate PWM frequencies available (0 - 7) and up to 16 outputs
with individually controlled duty cycle. You can output on either PWMnA or
PWMnB or both for each channel - no restriction
Minimum frequency is given by the equation
65535 < (OPTION CPUSPEED * 1000)/256
This gives a minimum frequuency of 7.5Hz with a clock speed of 125MHz
Maximum speed is OPTION CPUSPEED/4
Of course at very fast speeds the duty cycles will be increasingly limited

Valid channels for PWM and other special functions are given in the attached
table and the codes for SETPIN are as in the table.

Pin Ref   Possible modes
1   GP0   DIGITAL_IN | DIGITAL_OUT | UART0TX | SPI0RX | I2C0SDA | PWM0A
2   GP1   DIGITAL_IN | DIGITAL_OUT | UART0RX | I2C0SCL | PWM0B
3   GND                                                        
4   GP2   DIGITAL_IN | DIGITAL_OUT | SPI0SCK | I2C1SDA | PWM1A
5   GP3   DIGITAL_IN | DIGITAL_OUT | SPI0TX | I2C1SCL | PWM1B
6   GP4   DIGITAL_IN | DIGITAL_OUT | UART1TX | SPI0RX | I2C0SDA | PWM2A
7   GP5   DIGITAL_IN | DIGITAL_OUT | UART1RX | I2C0SCL | PWM2B
8   GND
9   GP6   DIGITAL_IN | DIGITAL_OUT | SPI0SCK | I2C1SDA | PWM3A
10  GP7   DIGITAL_IN | DIGITAL_OUT | SPI0TX | I2C1SCL | EXT_PWM3B
11  GP8   DIGITAL_IN | DIGITAL_OUT | UART1TX | SPI1RX | I2C0SDA | PWM4A
12  GP9   DIGITAL_IN | DIGITAL_OUT | UART1RX | I2C0SCL | PWM4B
13        GND 
14  GP10  DIGITAL_IN | DIGITAL_OUT | SPI1SCK | I2C1SDA | PWM5A
15  GP11  DIGITAL_IN | DIGITAL_OUT | SPI1TX | I2C1SCL | PWM5B
16  GP12  DIGITAL_IN | DIGITAL_OUT | UART0TX | SPI1RX | I2C0SDA | PWM6A
17  GP13  DIGITAL_IN | DIGITAL_OUT | UART0RX | I2C0SCL | PWM6B
18        GND 
19  GP14  DIGITAL_IN | DIGITAL_OUT | SPI1SCK | I2C1SDA | PWM7A
20  GP15  DIGITAL_IN | DIGITAL_OUT | SPI1TX | I2C1SCL | PWM7B

21  GP16  DIGITAL_IN | DIGITAL_OUT | UART0TX | SPI0RX | I2C0SDA | PWM0A
22  GP17  DIGITAL_IN | DIGITAL_OUT | UART0RX | I2C0SCL | PWM0B
23        GND 
24  GP18  DIGITAL_IN | DIGITAL_OUT | SPI0SCK | I2C1SDA | PWM1A
25  GP19  DIGITAL_IN | DIGITAL_OUT | SPI0TX | I2C1SCL | PWM1B
26  GP20  DIGITAL_IN | DIGITAL_OUT | I2C0SDA | PWM2A
27  GP21  DIGITAL_IN | DIGITAL_OUT | I2C0SCL | PWM2B
28        GND  
29  GP22  DIGITAL_IN | DIGITAL_OUT | PWM3A
30        RUN   
31  GP26  DIGITAL_IN | DIGITAL_OUT | ANALOG_IN | I2C1SDA | PWM5A
32  GP27  DIGITAL_IN | DIGITAL_OUT | ANALOG_IN | I2C1SCL | PWM5B
33        AGND 
34  GP28  DIGITAL_IN | DIGITAL_OUT | ANALOG_IN | PWM6A
35        VREF
36        3V3 OUT
37        3V3 ENABLE
38        GND
39        VSYS
40        VBUS

41  GP25  DIGITAL_OUT | PWM4B    Onboard LED so not wired out to a pin

------------------------
a20
I2C (channel 0) and I2C1 (channel 1) added.

SETPIN pin, I2C0SDA
SETPIN pin, I2C0SCL
I2C OPEN speed,timeout
I2C WRITE addr, option, sendlen, senddata [,senddata ...]
I2C READ addr, option, rcvlen, revbuf
I2C CLOSE

SETPIN pin, I2C1SDA
SETPIN pin, I2C1SCL
I2C1 OPEN speed,timeout
I2C1 WRITE addr, option, sendlen, senddata [,senddata ...]
I2C1 READ addr, option, rcvlen, revbuf
I2C1 CLOSE

------------------------
a21
SPI added
SPI[1] OPEN freq, mode [,bits]
Use SPI1 command and function for SPI1aaa pins and SPI for spi0aaa pins
bits per transfer can be between 4 and 16

SETPIN 19,SPI1SCK
SETPIN 20,SPI1TR
SETPIN 16,SPI1RX
SPI1 OPEN 1000000,0
? SPI1(123)

Change to SDcard options to prepare for LCD panels and touch
OPTION SYSTEM SPI CLKpin, MOSIpin, MISOpin

To define the pin that is used for the SDcard chip select
OPTION SDCARD CSpin  ** SEE a27 for changes **

Coming...
OPTION LCDPANEL type, RSpin, RESETpin, LCDCSpin
OPTION TOUCH CSpin, IRQpin

------------------------
a23
NAME command changed to RENAME
COPY fname1$ TO fname2$ added
MATH FFT added
PAUSE command improved

------------------------
a24
UARTS added, with partial testing

SETPIN 11, UART1TX
SETPIN 12, UART1RX
OPEN "COM1:115200" AS #1

SETPIN 1, UART0TX
SETPIN 2, UART0RX
OPEN "COM0:115200" AS #2

------------------------ 
a25
Fixes for LOF, LOC and EOF

------------------------ 
a26
Brought into line with new MMBasic Ver. 5.05.04
Speed improvements to SD card access.
Colours changed in the editor.

------------------------ 
a27
I2C display added for SSD1306 at default address 0x78/0x3c
OPTION SYSTEM I2C sdapin, sclpin
OPTION LCDPANEL SSD1306I2C, orientation

OPTION SDCARD can now have an additional argument:
OPTION SDCARD CSpin, speed
where speed is the speed of the SPI bus in MHz.Initially this defaults to
250kHz, but can be up to 20MHz if it works for you.

------------------------ 
a28
RTC GETTIME, SETTIME, GETREG, SETREG now all supported
Tested with DS3231 and PCF8563

------------------------ 
a29
More display support but no touch yet

Connecting SPI Based LCD Panels
The SPI based display controllers share the SYSTEM SPI channel (SPI2) interface
on the PicoMite with the touch controller (if present) and the SDcard. The pins
allocated to the SYSTEM SPI will not be available to other MMBasic commands.
The speed of drawing to SPI based displays will be laregely unaffected by the
CPU speed.

Connecting I2C Based LCD Panels
The I2C based display controllers use the SYSTEM I2C pins as per the pinout for
the specific device. Other I2C devices can share the bus subject to their
addresses being unique. If an I2C display is configured it will not be
necessary to "open" the I2C port for an additional device (I2C OPEN ),
I2C CLOSE is blocked, and all I2C devices must be capable of 400KHz operation.
The I2C bus speed is not affected by changes to the CPU clock speed

The PicoMite supports a wide range of displays. Not all tested

SSD1306 controller 128x64 pixel OLED, 0.96" and 1.3" with I2C I/F, monochrome
SSD1306 controller 128x32 pixel OLED, 0.1" with I2C I/F, monochrome
SSD1306 controller 128x64 pixel OLED, 0.96" and 1.3" with SPI I/F, monochrome
SSD1306 controller 128x32 pixel OLED, 0.1" with SPI I/F, monochrome
ST7920 controller 128x64 pixel LCD, 3.25" with SPI I/F, monochrome
Nokia 5110 controller 84x48 pixel LCD, with SPI I/F, monochrome
GDEH029A1 controller 128x296 pixel e-ink, with SPI I/F, monochrome
ILI9163 controller 128x128 pixel TFT, 1.44" with SPI I/F, RGB565
ILI9341 controller 320x240 pixel TFT, 2.2", 2.4", 2.8" with SPI I/F, RGB565
ST7735 controller 160x128 pixel TFT, 1.8" with SPI I/F, RGB565
ST7735S controller 160x80 pixel IPS, 0.96" with SPI I/F, RGB565
SSD1331 controller 96x64 pixel OLED, 0.95" with SPI I/F, RGB565
ST7789 controller 240x240 pixel IPS, 1.3" with SPI I/F, RGB565
ILI9481 controller 480x320 pixel TFT, 3.5", 4" with SPI I/F, RGB565
ILI9488 controller 480x320 pixel TFT, 3.5", 4" with SPI I/F, RGB666

** See Displays.txt file for specific info on each display setup **

------------------------
a30 a31
SD card bugfixes

------------------------
a32
Load and save image now working NB: save image only for ILI9341
BLIT and transparent text also working for ILI9341
ARC implemented - untested

------------------------
a33
SD card bitbang, combined with SPI displays, on same pins

------------------------
a34
HUMID becomes BITBANG HUMID
adds

BITBANG BITSTREAM as per CMM2 manual


BITBANG WS2812 type, pin, number _of_leds, data

If number _of_leds is one then the data can be anything that yields a number
between 0 and &HFFFFFF. If number _of_leds is > 1 then data should be an
integer array

Note minor change from CVMM2 syntax to allow a single LED to be used
(e.g.Maker board)
Try BITBANG WS2812 B,34,1,rgb(red) on the maker board

------------------------
a35
Touch screen working
GUI test touch
GUI test lcdpanel
GUI BEEP n
GUI RESET LCDPANEL
GUI CALIBRATE
TOUCH(X)
TOUCH(Y)
OPTION TOUCH CSpin, IRQpin [,BEEPpin]

OPTION POWER PWM|PFM is now a permanent option & is executed on boot
The default mode from newly powered up or OPTION RESET is PFM.

IR is working, on any pin
SETPIN pin, IR
IR dev, key, int
IR CLOSE  (I assume!)

------------------------
a36
Added: option to auto-load time$ & date$ on boot & every hour
OPTION RTC AUTO ENABLE/DISABLE

Added: in readiness for adding GUI controls
OPTION MEMORY No_of_GUI_controls, program_memory_size
There is a pool of 160k of RAM which can be allocated.
You have to have twice as much RAM as your program size otherwise you can't
edit it.
Decide how many controls you want:
ControlsRAM = <num_of_controls>*52 bytes rounded up to next 256 byte multiple.
FreeRAM is 160k - ControlsRAM
You can allocate up to 1/2 of FreeRAM as program space, the rest is used for
both variables and editing. You could allocate, say, just 20k to the program
to get some bigger arrays or a large number of variables or something..

------------------------
a37
Full GUI functionality now implemented
DISTANCE function now implemented (Take care HR-SR04 need 5V and PicoMite
pins are not 5V safe - use a level converter)

------------------------
a38
Now supports setpin n, FIN, PIN,and CIN. Set up using:
OPTION COUNT pin1, pin2, pin3, pin4
These default to GP6, GP7, GP8 and GP9 on a newly powered PicoMite or after
an OPTION RESET. If you load A38 to an existing PicoMite you will need to
execute the option command,There is no restriction on which pins are used.

VAR SAVE
VAR RESTORE
VAR CLEAR
allow a 16k area to be used for variable storage.

------------------------
a39
Bugfix

------------------------
a40
Now has the same 7 built-in fonts as the CMM2.

------------------------
a41
Adding PIO conrol commands:
PIO INIT MACHINE pio%, statemachine%, clockspeed [,pinctrl] [,execctrl]
 [,shiftctrl]

e.g.
Dim a%(7)=(&H0001E000E101E081,0,0,0,0,0,0,0)
SetPin 1,pio0
PIO program 0,a%()
PIO init machine 0,0,100000
PIO start 0,0

generates a square wave on pin-1 at 1/4 of the clock frequency requested.


------------------------
a42
Lots of new stuff to control the PIO system.

* PIO Commands *
Immediately executes the instruction on the pio and state machine specified.
PIO EXECUTE pio, state_machine, instruction%

writes the data elements to the pio and state machine specified. The write
is blocking so the state machine needs to be able to take the data supplied
NB: this command will probably need additional capability in future releases
PIO WRITE pio, state_machine, count, data0 [,data1....]

reads the data elements from the pio and state machine specified. The read
is non-blocking so the stat machine needs to be able to supply the data
requested. NB: this command will probably need additional capability in future
releases
PIO READ pio, state_machine, count, data%()

This says to set up a statemachine for the specified PIO with a given clock
speed. The user is then required to specify the three registers which control
how the PIO will operate. See the manual for details. It is anticipated that
eventually the assembler will be able to generate the register values for the
user along with the program array based on the defined assembler directives.
something in Basic
PIO INIT MACHINE pio, statemachine, clockspeed, PINCTRL register
EXECCTRL register, SHIFTCTRL register

Starts or restarts a specific state machine
PIO START pio, statemachine

Stops a specific state machine
PIO STOP pio, statemachine 


* PIO() Functions *
helper function to calculate the value of pinctrl for the INIT MACHINE command 
PIO(PINCTRL no_side_set_pins [,no_set_pins] [,no_out_pins] [,IN base]
 [,side_set_base] [,set_base]) 

helper function to calculate the value of execctrl for the INIT MACHINE command
PIO(EXECCTRL jmp_pin ,wrap_target, wrap

helper function to calculate the value of shiftctrl for the INIT MACHINE command 
PIO(SHIFTCTRL push_threshold [,pull_threshold] [,autopush] [,autopull])

returns the value of the FSTAT register for the pio specified
PIO(FSTAT pio)

returns the value of the FSDEBUG register for the pio specified
PIO(FDEBUG pio)

returns the value of the FLEVEL register for the pio specified
PIO(FLEVEL pio)

------------------------
a43
A special update that doesn't even metion the PIO! :)

DEFINEFONT #n   now working
OPTION PIN nbr  now working

------------------------
a44
New PIO Commands:

This stops the pio specified on all statemachines and clears the control
registers for the statemachines PINCTRL, EXECTRL, and SHIFTCTRL to defaults
PIO CLEAR pio

Programs just the specified line in a PIO program
PIO PROGRAM LINE pio, line, instruction

------------------------
a45

KEYPAD and LCD comands added.
Note you should use a 3.3V LCD as in the picture - they are available.

Added a new text file for the PIO stuff as it's taking on a life of its own!
All exampples etc. will be in the new file.

------------------------
a46
Bugfix

------------------------
a47
Background GPS processing now implemented as per CMM2
OPEN "COMn:baud" as GPS [,time_offset_from_UTC_in_hours] [,monitor_on]
CLOSE GPS
PRINT #GPS,"string$"
GPS function e.g. ? GPS(TIME)

A good use is:

rtc settime gps(date)+" "+gps(time)

------------------------
a48
udio

Setting up audio takes one of the PWM channels

OPTION AUDIO PWMnApin, PWMnBpin

e.g.

OPTION AUDIO GP18,GP19

This is a permanent option and blocks other use of the pins. As the audio output is generated using PWM you will need a low pass filter on the output (e.g. the circuit on the CMM1)

You can then use the following commands as per the CMM2

PLAY TONE
PLAY SOUND (but not the noises)
PLAY WAV (up to stereo at 48KHz)

I haven't implemented PLAY MP3 or PLAY FLAC as they take too much working memory and would have unacceptably reduced memory availability for programs and/or variables.

Note though the power supply on the Pico board is CATASTROPHIC

Everything the CPU does can be heard on the audio - in particular reading from the SDcard. Look at the signals on a scope and you will see massive spikes on the lines.
I would strongly recommend if you want to use the audio you use a separate 3.3V supply (preferably with a linear regulator) and turn off the Pico supply by grounding the 3V3_EN pin

------------------------
